Skip to content

Make mining a verified one-command path - #14

Open
adamtpang wants to merge 4 commits into
Quantus-Network:mainfrom
adamtpang:codex/one-command-mining-9-9
Open

Make mining a verified one-command path#14
adamtpang wants to merge 4 commits into
Quantus-Network:mainfrom
adamtpang:codex/one-command-mining-9-9

Conversation

@adamtpang

Copy link
Copy Markdown

Overview

Replace the current multi-decision mining setup with one verified Planck testnet route. A first-time user downloads the installer, verifies its checksum, runs ./quantus-mining.sh mine, enters the wallet recovery phrase only into a hidden local prompt, and receives one status contract.

This change does not claim mainnet support, a launch date, monetary rewards, or unpublished platform support.

Before and after

Area Before After
Release selection Node and miner resolved independent latest releases One machine-readable pair: node v0.10.0, miner v4.0.2, protocol quantus-miner/2
Download integrity Binaries installed without digest checks Every release asset must match its official GitHub SHA-256 digest before installation
Beginner path Several commands and resource, name, network, and version decisions One daily command, one hidden local recovery-phrase prompt, automatic conservative defaults
Success state Users inspect separate processes and logs status reports network, pair, node, sync, miner, hash rate, reward address, telemetry, and recovery action
Restart proof No explicit contract restart-check stops, restarts, and verifies both processes
Desktop app Draft page linked to the repository's generic latest release Public preview page with direct Windows, macOS, and Linux assets plus exact verification commands
AI handoff Mining skill only Copy Context includes the skill, pinned compatibility manifest, and full guide

What changed

  • Add static/mining-compatibility.json as the single supported Planck release manifest.
  • Pin official chain, miner, and desktop app URLs and SHA-256 digests.
  • Make mine, status, and restart-check the primary installer commands.
  • Fail closed on unsupported network, protocol, platform, URL, asset name, version, or checksum.
  • Keep the recovery phrase in a hidden local prompt and out of config, logs, command history, telemetry, and copied AI context.
  • Store the derived reward preimage in an owner-only file instead of the public configuration file.
  • Replace the mining guide with a three-step quick start, one AI prompt, one status contract, and one recovery action per failure.
  • Publish the desktop app as an explicitly limited preview with direct platform downloads.
  • Add automated manifest, platform, compatibility, checksum, redaction, command, prompt, and installer-byte tests.

Validation

  • bun run typecheck
  • bun test: 13 tests, 103 assertions, 0 failures
  • bun run build
  • Git Bash syntax check: bash -n static/scripts/quantus-mining.sh
  • Official GitHub release API comparison: all 17 release assets matched the manifest URLs and digests
  • Helium browser QA at desktop and 390 x 844 mobile viewports
  • Rendered routes, direct downloads, compatibility manifest, installer, checksum, and Copy Context verified
  • No page-wide horizontal overflow on either guide
  • git diff --check

The build completes with the repository's existing stale Browserslist-data warning and the existing vscode-languageserver-types dynamic-require warning.

Owner facts before merge

  1. A Quantus release owner should confirm v0.10.0 plus v4.0.2 as the supported pair. The current evidence is the official miner v4.0.0 release note requiring node v0.10.0+.
  2. Minimum supported Windows, macOS, and Linux versions are not published. The manifest says not-published instead of inventing values.
  3. The chain currently accepts --rewards-inner-hash only as a process argument. This patch protects the value at rest with owner-only permissions, but it remains visible to local process inspection while the node runs. A follow-up chain change should add --rewards-inner-hash-file or an equivalent secret-input mechanism.
  4. Quantus does not currently publish signed compatibility metadata. This patch verifies HTTPS-delivered metadata and official GitHub asset digests, but the manifest and installer checksum are not signed. A release owner should establish a signing key and signed manifest flow.
  5. Desktop app miner-v0.6.1 independently downloads the latest chain and miner releases and does not verify them. It remains a preview until it consumes the shared manifest and verifies every runtime download.
  6. The verified Windows route is WSL2. Native Windows remains on the desktop preview path.

Scope

This PR changes documentation, static release metadata, the existing installer, Copy Context, and tests. It does not merge, deploy, publish a release, run a real wallet, or change chain or miner binaries.

Pin one supported Planck node and miner pair in a machine-readable compatibility manifest.

Verify release checksums before installation, keep wallet recovery input local, add clear status and restart checks, and publish direct desktop preview downloads with platform verification commands.

Add automated compatibility, checksum, redaction, command, and documentation tests.
adamtpang and others added 3 commits September 5, 2026 14:01
The installer is published with a SHA-256 file, and a test asserts that the
checksum matches the exact bytes in the repository. On a Windows clone with
core.autocrlf=true, git rewrites the script to CRLF on checkout, the bytes no
longer match, and the test fails for a reason that has nothing to do with the
installer. The same rewrite would make a locally built docs site serve a
script whose checksum does not match its own .sha256.

.gitattributes now pins LF for the installers, their checksum files, and the
compatibility manifest. The four files are renormalized in the same change.

The bash-backed tests also stop spawning a login shell. bash -lc sources the
developer's profile, and anything it prints (a clear-screen escape, a greeting)
lands in the captured stdout and breaks exact-match assertions. --noprofile
--norc runs the same commands in a clean shell, which is what CI does anyway.

On this Windows machine the suite goes from 3 failures to 0 with no change to
what is being tested.

Co-Authored-By: Claude Fable 5.1 <noreply@anthropic.com>
The guide told Windows users to open WSL2 or try the desktop app preview.
Neither is a working GPU path. Under WSL2 the miner's wgpu backend has no
reliable route to the host GPU, and the desktop app is a preview that does not
pin or verify what it downloads. Meanwhile the compatibility manifest already
carried Windows URLs and checksums for both binaries, and the chain's own
MINING.md documents the native MSVC node as supported.

Verified by hand on a Windows 11 laptop with an RTX 3070 before writing any
of this, using only the manifest's Windows assets:

  node v0.10.0     starts on Planck natively, no WSL, syncs at ~175 blocks/s,
                   writes miner-auth-token and miner-tls-cert-sha256
  miner v4.0.2     SHA-256 matches the manifest, benchmarks at 33.6 MH/s on
                   the discrete GPU, and against the node: authenticates,
                   registers, receives job 1, returns a Completed result
  key quantus      --scheme wormhole --words re-derives the same address and
                   inner hash from a phrase on stdin, so the hidden prompt works
  system_syncState exposes current and highest block over RPC on 9944

quantus-mining.ps1 is a twin of quantus-mining.sh, not a port of its text:
same commands (mine, setup, status, start, stop, restart, restart-check,
config, uninstall), same manifest fields, same fail-closed checks on network,
protocol, release URL, asset name and checksum, same pair probe on --help,
same hidden recovery-phrase prompt with the phrase passed on stdin only, same
owner-only files for the config and the reward preimage, same redaction in
status, same status contract. Where Windows differs it says so in a comment.

Two things the Windows status does that the shell one does not yet:

  - While syncing, it shows block, target, rate and time left, measured over a
    five second window from system_syncState. Full sync is the only mode this
    node supports (warp reports no provider, fast refuses on archive nodes),
    and it takes one to a few hours. Saying "Syncing" for two hours is the
    single worst part of the newcomer experience; a number that moves is not.
  - It detects the Windows Defender stall MINING.md warns about (peers
    connected, block number not moving) and prints the one-time elevated
    command as the single recovery action, instead of leaving the user to
    diagnose it. The exclusion itself is left to the user: it is a security
    setting, and the installer never elevates.

The guide gains a PowerShell download-and-verify block beside the curl one,
opens with "open a shell" instead of "open WSL2", and gets two Windows rows in
the recovery table. The skill routes native Windows to the .ps1 and no longer
sends anyone to the app preview. The shell installer's unsupported-OS message
now names the .ps1. quantus-mining.ps1.sha256 is published beside it, and the
shell installer's checksum is regenerated for its one changed line.

mining.conf.example still showed INNER_HASH inside the public config, which
the installers stopped doing in this branch; it now matches what they write.

Tests: seven new cases. Static ones check the command contract, the manifest
keys the script reads, that the phrase never reaches the command line or the
config, that the guide and skill point Windows at the .ps1, and that the
published checksum matches the bytes. Behaviour ones parse the script with
PowerShell's own parser and exercise manifest loading, protocol classification,
fail-closed checksums and redaction by dot-sourcing it; they run on pwsh or
Windows PowerShell and skip where neither exists, so a Linux runner without
pwsh still passes the static half. Parsed clean on both PowerShell 7.6 and
Windows PowerShell 5.1, which ships with Windows.

Not done here: a run of the installer's own download path on a clean Windows
machine, which needs the 23 MB node archive fetched through the script rather
than by hand. Everything downstream of that download is what was verified
above.

Co-Authored-By: Claude Fable 5.1 <noreply@anthropic.com>
Publish a plain Markdown setup prompt and link it before manual prerequisites. Reuse the pinned compatibility manifest and verified installer flow; pause for private wallet input and distinguish syncing from mining.

Add endpoint/link/safety tests and allow 20 seconds for the existing five-process PowerShell test. Validation: typecheck, 23 passing tests, production build, published artifact hash and guide-link checks. No live mining validation performed.
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant